home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 25 / CU Amiga Magazine's Super CD-ROM 25 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-08].iso / CUCD / Programming / QuakeTools / docs / qtools.doc
Text File  |  1998-06-12  |  17KB  |  433 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                     QuakeTools-library
  7.                                        Version 0.1
  8.                      Copyright © by Niels Froehling (Dyna-Tech) 1998
  9.  
  10.  
  11.        idea:
  12.        
  13.          the intention to write this was to bind all the (sometimes not easy to find) basic
  14.          functions to create and modify all the different files of quake. i know, there are
  15.          allready the sources from mr. carmack, but ive written lots of extensions, sometimes
  16.          his code is a bit confusing, and as we all now we can read own code better than code
  17.          from others :).
  18.          this is an open project, so any programmer who wants to put his ideas or descriptions
  19.          into this, can join. there is so much left and undocumented i havnt enough time to do
  20.          all of it.
  21.          as a beginning this code could act as a quake-dokumentation-project too (eg. combined
  22.          together with "the unofficial quake-faq").
  23.        
  24.        contact:
  25.        
  26.          email
  27.           <Niels.Froehling@Informatik.Uni-Oldenburg.DE>
  28.           
  29.          snailmail
  30.           Niels Froehling
  31.           Bardieksweg 28
  32.           26125 Oldenburg
  33.           Germany
  34.        
  35.        status:
  36.        
  37.      This program is free software; you can redistribute it and/or modify
  38.      it under the terms of the GNU General Public License as published by
  39.      the Free Software Foundation; either version 2 of the License, or
  40.      (at your option) any later version.
  41.  
  42.      This program is distributed in the hope that it will be useful,
  43.      but WITHOUT ANY WARRANTY; without even the implied warranty of
  44.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  45.      GNU General Public License for more details.
  46.  
  47.      You should have received a copy of the GNU General Public License
  48.      along with this program; if not, write to the Free Software
  49.      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  50.  
  51.          read it carefully, aspecialy if you drive windows or something like that.
  52.          
  53.          bsptomap:
  54.           "you are free to use this program
  55.            you are free to use/modify/compile source code
  56.            you can do anything you want with it"
  57.           means: the code from bsptomap falls under the GPL too
  58.          
  59.          qutils/exdawn:
  60.           no comment about copyrights
  61.           means: the code from qutils falls under the GPL too
  62.          
  63.          unqcc:
  64.           "Do whatever you like with it."
  65.           means: the code from qcc falls under the GPL too
  66.          
  67.          summary:
  68.           ALL of this code falls under the GPL. in short: every modification of the code
  69.           must be reported and send to the programmer(s) of this code, and is distributed
  70.           under the GPL too.
  71.           you are NOT allowed to take money more than the costs of the medium on it is copied.
  72.        
  73.        programmer(s)/credits:
  74.        
  75.          Janis Jagars <ppsaikne@mail.vernet.lv>
  76.          John Carmack <???>
  77.          Christian Knauer <cnknauer@cip.informatik.uni-erlangen.de>
  78.          Ben Cohee <benco@gisco.net>
  79.          Niels Froehling <Niels.Froehling@Informatik.Uni-Oldenburg.DE>
  80.        
  81.        maintainer:
  82.        
  83.          Niels Froehling <Niels.Froehling@Informatik.Uni-Oldenburg.DE>
  84.          
  85.        options:
  86.  
  87.      -c <colormap>       quake colormap lump
  88.      -d <destdir>        alternative destination directory including "/" at the end
  89.      -dither [<value>]   dither floyd-steinberg with this error
  90.                   (a little bit complicate: the standard error diffusion
  91.                    with floyd steinberg is to divide by 16 and add con-
  92.                    stant parts of the error to neighnour pixels. the value
  93.                    is valid from 16 to 256 which means: is the error-ammount
  94.                    for a pixel 3 we use 3/16 of the error in default. if the
  95.                    amount is 32 we use 3/32, so the error-diffusion is halfed.
  96.                    in general we could say, the higher the value, the less
  97.                    qtools do error-diffusion (an invinite value means NO
  98.                    error-diffusion, in practice the errors maximum is 256).
  99.                    default is 16.
  100.      -smooth [<value>]   smooth the pictures while converting (valid from 1 to 256)
  101.                   meaning, all upto 256th of the 8 neighbour-pixels influences
  102.                   the original pixel-color. default is 2.
  103.      -l <darkness>       take this darkness-level
  104.      -lump/-mip          specifies pic-conversion (in general for directory-
  105.                   conversions without "-o")
  106.      -mip0               store only the first mip instead of all four (only
  107.                   for wads)
  108.      -lz                 compress data with lz77 (only for wads)
  109.                  (only available in the executeable for amiga, i will
  110.                   compile it for other 68k-systems on demand. its my
  111.                   algorithm and my implementation, so im not interesting
  112.                   in a publication for free (eah, i do only have 68k-code))
  113.      -ns                 do not write index-files
  114.      -o <file>           specify archive-content or output-name
  115.      -p <palette>        quake palette lump
  116.      -ppm/-jpg/-png         convert pictures and palettes to ppm/jpg/png
  117.      -r                  recurse extracting
  118.      -<qbsp/light/vis>   support for ALL option that qbsp, light and vis have. except
  119.                   threads
  120.      -waterlit         water and slime get shadows
  121.      -watervis         look through water (GLQuake)
  122.      -slimevis         look through slime (GLQuake)
  123.      -pp "<commandline>" you can specify a preprocessor like cpp to parse
  124.                   QuakeC-files before the compiler. if you want to give
  125.                   commandlines to it, it is a must to set quotation-marks
  126.                   (eg. "cpp -P" is perfectly valid), afterwards qtools inter-
  127.                   prets the commandline for itself
  128.  
  129.        commands:
  130.  
  131.      a                   add
  132.      d                   delete (unimplemented)
  133.      l                   list (default)
  134.      r                   replace (unimplemented)
  135.      u                   update (unimplemented)
  136.      v                   view (unimplemented)
  137.      x                   extract
  138.  
  139.        environment:
  140.     
  141.      QUAKE_PALETTE         the location of the default "palette.lmp"
  142.                   (default is "palette.lmp")
  143.      QUAKE_COLORMAP         the location of the default "colormap.lmp"
  144.                   (default is "colormap.lmp")
  145.      QUAKE_WADFILE         the location of the default wad for bsps, you can put more than
  146.                   one wad into the line: "test1.wad; medivial.wad; rogue.wad"
  147.                   (no default)
  148.      QUAKE_WADDIR         the location of the default directory to parse for miptexs, you
  149.                  can put more than one dir into the line: "test1.wad; medivial.wad;
  150.                  rogue.wad"
  151.                   (default is current directory)
  152.  
  153.        extensions:
  154.        
  155.     floating points in every data-file qbsp/vis uses: map/prt/h?/pts
  156.     
  157.     multiple wads in the "wad" and "_wad" keywords: "test1.wad; medivial.wad; rogue.wad"
  158.     of map-files
  159.     
  160.     "dir" keyword in map files, if qtools scans for textures in bsp-creation, it scans
  161.     the dirs (non-recursive) and loads the textures from every fileformat it can load
  162.     multiple dirs are valid too: "test1.dir; /tmp/medivial-contents; ~/crap-tests"
  163.     (it does NOT search for wads in these directories, only images)
  164.  
  165.        some features in short:
  166.        
  167.         read/writes picture formats:
  168.         
  169.          ppm/pgm/png/jpg
  170.         
  171.         read/writes 3d formats:
  172.         
  173.          tddd
  174.          
  175.         read/writes quake formats:
  176.         
  177.          wad/(bsp/vis/lit/prt/h?/map)/pak/(qc/dat)/mip/lmp
  178.          
  179.         others:
  180.         
  181.          can compress wads
  182.          can use fs-dithering
  183.          uses high quality mipmap-scaling
  184.          build in script-system with recursion-capabilities
  185.          can load pictures directly into bsps
  186.          uses less memory
  187.          error robust
  188.          can parse entire directories and perform the default actions to every file
  189.           and subdirectory
  190.          can extract bsp/pak recursively
  191.  
  192.        available modes (examples):
  193.     
  194.     notes:
  195.     
  196.      qtools is able to read AND write all of its datas, so you could
  197.      make make it a ppm2png-converter or vice versa with the limitation, that the
  198.      pictures will be remapped to the quake-colors, but that need not to be a
  199.      limitation, maybe a feature.
  200.      
  201.      sometimes you can suspress the "x" if you define a clear (from the program
  202.      understandable) output like "qtools quake.wad -o *slime1".
  203.      
  204.      sometimes you can suspress the "a" if you define a clear (from the program
  205.      understandable) output like "qtools *slime1.mip -o quake.wad"
  206.      
  207.      it is possible to emulate some behaviours of other programs like mergewad:
  208.      
  209.       to merge to wads you should type something like this:
  210.       
  211.        qtools a first.wad -o merged.wad
  212.        qtools a second.wad -o merged.wad
  213.        qtools a third.wad -o merged.wad
  214.        qtools a fourth.wad -o merged.wad
  215.        ...
  216.       
  217.       to sub wads:
  218.       
  219.        qtools v first.wad
  220.        rename first.idx delfirstinmerged.idx
  221.        replace "update" with "delete" in delfirstinmerged.idx
  222.        replace "first.wad" with "merged.wad" in delfirstinmerged.idx
  223.        qtools delfirstinmerged.idx
  224.       
  225.      qtools does not extract wads out of paks nor converts pictures. you will
  226.      get the raw data only. try "-r" for recursive, then all the contents of
  227.      the pak will be postprocessed by qtools. WARNING: recursive means really
  228.      recursive: pak->bsp->wad->pic and pak->bsp->map or pak->dat->src. every-
  229.      thing will be processed!
  230.     
  231.      the format of "-o <file>" is very error-resistent. these:
  232.       -o *slime1
  233.       -o *slime1.
  234.       -o *slime1.<whatever you think>
  235.      extract surely "*slime1" out of bsps and wads.
  236.      one exception is "-o *slime1.<whatever you think>":
  237.       -o *slime1.ppm            extracts to a ppm
  238.       -o *slime1.png            extracts to a png
  239.       -o *slime1.<whatever other you think> extracts to a raw-mipmap
  240.      mipmap does not have any identifiers, its up to you to remember, which
  241.      files are mips and which not.
  242.     
  243.      there are some special word on bsps. i have split up the definition of a
  244.      bsp in several parts:
  245.       test.bsp
  246.      contains
  247.       test.map (decompiled bsp, map-format)
  248.       test.iob (decompiled bsp, imagine-object-format)
  249.       test.wad (textures)
  250.       test.lit (raw)
  251.       test.vis (raw)
  252.      so if you type "qtools x test.bsp -o test.vis" you get the raw-visdata.
  253.      all names, that are not of the form "<filebase>.<map/wad/lit/vis>" are
  254.      accepted as texturenames. "qtools x test.bsp -o *slime1" extracts the
  255.      texture "*slime1" seperatly.
  256.     
  257.     directory-structures and default outputs:
  258.     
  259.      if the output-name do not specify an alternate directory (like: -o /tmp/test.map)
  260.      all files will be saved to <filebase>.<dir>/<filebase>.<ext> or (in case of
  261.      qtools test1234.bsp -o test4321.map) <oldfilebase>.<dir>/<newfilebase>.<ext>
  262.      
  263.      if you specify a destdir, its the same as above <destdir>/<filebase>.<dir>/<filebase>.<ext>
  264.      except you do something like this: qtools -d /tmp/ test.bsp -o /tmp2/bla/test.map
  265.      produces without checking /tmp/tmp2/bla/test.map, which is invalid. in that case
  266.      the dirpart of the output is stripped resulting in /tmp/test.dir/test.map
  267.      
  268.      it is reommended to use the default hierarchy the program offers and move data
  269.      only via directories or partitions, leave the structure in it intact:
  270.      
  271.      /quake
  272.      /quake/id1
  273.      /quake/id1/pak0.pak                (results from below)
  274.      /quake/id1/pak0.idx                (file to build data recursive)
  275.      /quake/id1/pak0.dir
  276.      /quake/id1/pak0.dir/progs.dat            (results from below)
  277.      /quake/id1/pak0.dir/progs.dir
  278.      /quake/id1/pak0.dir/progs.dir/progs.src
  279.      /quake/id1/pak0.dir/progs.dir/*.qc
  280.      /quake/id1/pak0.dir/gfx
  281.      /quake/id1/pak0.dir/maps
  282.      /quake/id1/pak0.dir/maps/start.bsp        (results from below)
  283.      /quake/id1/pak0.dir/maps/start.dir
  284.      /quake/id1/pak0.dir/maps/start.dir/start.map
  285.      /quake/id1/pak0.dir/maps/start.dir/start.wad
  286.      /quake/id1/pak0.dir/maps/start.dir/start.prt
  287.      /quake/id1/pak0.dir/maps/start.dir/...
  288.      /quake/id1/pak0.dir/progs
  289.      /quake/id1/pak0.dir/sound...
  290.     
  291.     patterns:
  292.     
  293.      all form of patterns are allowed so
  294.       qtools -png -r -wad x *.bsp blabla/*.wad ../pak*.pak
  295.      extracts _all_ contents of matching files, all pictures will be converted
  296.      to png-pictures, the rest will be stored as is. additional the resulting
  297.      wad from the bsps will be converted to pngs and all contents of the pak
  298.      will be postprocessed (wad->pictures, bsp->wad->pictures, bsp->map ...).
  299.      
  300.      on some OSs the character "*" is reserved for pattern-matching (i think
  301.      dos and windows and nt are the only one). as a result on that platforms
  302.      you are NOT able to extract warp-textures that begins with a "*" (bsp->wad
  303.      is okay). hint: buy something like linux. [evilgrin]
  304.     
  305.     defaults:
  306.     
  307.      qtools test.bsp
  308.       list the contents of the bsp, that means all textures and the statistics
  309.      
  310.      qtools test.idx
  311.       processes the script "test.idx"
  312.      
  313.      qtools test.pak
  314.       list the contents of the pak
  315.      
  316.      qtools test.wad
  317.       list the contents of the wad
  318.      
  319.      qtools test.dir
  320.       processes all files and directories in test.dir with the defaults above
  321.      
  322.     extracts:
  323.     
  324.      qtools x test.bsp
  325.       extracts the contents of the bsp, that means all textures and the statistics
  326.      
  327.      qtools x test.idx
  328.       processes the script "test.idx"
  329.      
  330.      qtools x test.pak
  331.       extracts the contents of the pak
  332.      
  333.      qtools x test.wad
  334.       extracts the contents of the wad
  335.      
  336.      qtools x test.dir
  337.       processes all files and directories in test.dir with the defaults above
  338.      
  339.     modifiers:
  340.  
  341.      qtools -ppm *.mip
  342.       converts all mips to ppm
  343.       
  344.      qtools -png *.mip
  345.       converts all mips to png
  346.  
  347.      qtools -mip *.png -o png.wad
  348.       converts all pngs to mipmaps in pngs.wad
  349.       
  350.      qtools -mip -dither 16 *.png -o png.wad
  351.       converts all pngs to mipmaps in pngs.wad with dither and error diffusion of 1
  352.       
  353.      qtools -lump *.png -o png.wad
  354.       converts all pngs to consolepics in pngs.wad
  355.       
  356.      qtools -mip -mip0 *.png -o png.wad
  357.       converts all pngs to mipmaps that contains only the first mipmap in pngs.wad
  358.       (probably not readable for other tools)
  359.      
  360.       qtools -mip -lz *.png -o png.wad
  361.       converts all pngs to mipmaps in pngs.wad that are compressed
  362.       (surely not readable for other tools)
  363.       
  364.      qtools -mip -mip0 -lz *.png -o png.wad
  365.       converts all pngs to mipmaps that contains only the first mipmap in pngs.wad
  366.       and that are compressed
  367.       (surely not readable for other tools)
  368.  
  369.      qtools -ppm -d /usr/home/quake *.mip
  370.       converts all mips to ppm in the directory /usr/home/quake
  371.       
  372.      qtools -png *.mip -p /bullshit/quake/zer/gfx/colormap.lmp
  373.       converts all mips to png and uses the /bullshit/quake/zer/gfx/colormap.lmp
  374.       colormap instead of quakes (same for palettes)
  375.  
  376.        scripting:
  377.  
  378.     common commands:
  379.      "process <file>.<ext>"               -> take this file upto
  380.      "finish <file>.<ext>"                -> here
  381.      "list <file>.<ext>"              -> list the contents
  382.      "view <file>.<ext>"              -> view the pictures or texts in a window, or whatever
  383.  
  384.      sub-commands:
  385.       "update <file>.<ext> as <name>"     -> add if not exists, replace if newer
  386.       "replace <file>.<ext> as <name>"    -> replace if exists, do NOT add
  387.       "add <file>.<ext> as <name>"        -> add if not exists, do NOT replace
  388.       "delete <name>"                     -> delete if exists
  389.       "extract <name> as <file>.<ext>"    -> extract if exists
  390.  
  391.         currently implemented are only add/extract
  392.         
  393.        todo:
  394.        
  395.         use zlib instead of own compression algorithm? (already in, but only used for png)
  396.         make-like timestamp-updating?
  397.         lot of dokumentation (the whole source)
  398.         support for quake2
  399.         support fr the extensions of bsp/worldcraft/...
  400.         ... (too much)
  401.  
  402.        used code:
  403.        
  404.         ive ripped code from
  405.         
  406.          qcc      - look at ripped/quakeutils.txt
  407.           modified to use autoexpanded memory-pools
  408.          
  409.          qbsp     - look at ripped/quakeutils.txt (also used: hipnotics qbsp)
  410.           modified to use autoexpanded memory-pools
  411.           modified to make waterleafs and/or slimeleafs visible
  412.           modified to use dynamic face-sizes
  413.           modified to read from special wads and entire directories with pictures (ppm/png/jpg/mip/lmp)
  414.           modified to read and write floating points to and from every textfile (better accuracity)
  415.           modified to read multiple wads
  416.           modified to scan multiple dirs
  417.           
  418.          light    - look at ripped/quakeutils.txt (also used: hipnotics light)
  419.           modified to use autoexpanded memory-pools
  420.           modified to make water and/or slime with lightstyles
  421.           modified to make the qrad3-algorithms available to quake1
  422.           
  423.          vis      - look at ripped/quakeutils.txt
  424.           modified to use autoexpanded memory-pools
  425.           modified to read floating points from portal-file
  426.  
  427.          unqcc    - look at ripped/unqcc099.txt
  428.           modified to use autoexpanded memory-pools (unqcc itself contains code from advqcc4)
  429.  
  430.          bsptomap - look at ripped/bsptomap.txt
  431.           completly rewritten, only the concept is used
  432.  
  433.